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How  to  Use  CGWAVE  with  SMS: 
An  Example  for  Tedious  Creek 
Small  Craft  Harbor 

by  Michael  J.  Briggs,  Barbara  P.  Donnell,  and  Zeki  Demirbilek 

PURPOSE:  This  Coastal  and  Hydraulics  Engineering  Technical  Note  (CHETN)  presents  an 
example  of  how  to  use  the  numerical  model  CGWAVE  within  the  Surface  Water  Modeling  System 
(SMS)  Version  8.0  environment.  Updates  of  SMS  are  frequent  and  may  result  in  different  control 
options.  This  CHETN  was  completed  as  part  of  the  Tedious  Creek,  MD,  work  unit  of  the  Monitoring 
Completed  Navigation  Projects  program. 

BACKGROUND:  The  SMS  is  a  comprehensive  graphical  user  interface  (GUI)  for  model  con¬ 
ceptualization,  mesh  generation,  statistical  interpretation,  and  visual  examination  of  surface-water 
model  simulation  results.  The  version  described  herein  is  SMS  Version  8.1.  It  is  the  main  model 
delivery  system  with  pre-  and  post-processor  capabilities  for  all  the  CHL  numerical  models 
including  ADCIRC,  TABS  (RMA2,  RMA4,  SED2D),  ADH,  HiVEL,  M2D,  STWAVE,  BOUSS2D, 
and  CGWAVE.  These  integrated  or  interconnected  models  provide  circulation  and/or  wave  climate 
from  a  range  of  coastal  processes  including  waves  and  currents,  sediment  transport  and  morphology 
change,  channel  infilling  and  inlet  morphology,  and  dredged  material  fate.  SMS  provides  the  tools 
and  macros  for  editing  and  display  for  mesh  development,  coordinate  conversion,  model  con¬ 
nectivity,  animations,  and  comparisons. 

SMS  is  divided  into  modules.  The  modules  discussed  herein  are:  Scatter,  Map,  and  Mesh.  The 
Scatter  module  stores  scattered  data  sets,  such  as  bathymetric  data,  and  interpolates  them  to  model 
grids  and  meshes.  The  Map  module  is  used  to  create  and  manipulate  conceptual  models.  The  user 
can  create  and  define  attributes  for  feature  objects,  such  as  points,  arcs  and  polygons,  which  define 
the  system  being  modeled.  Images,  such  as  scanned  maps  or  photographs  can  be  helpful  in  this 
process  and  also  make  the  display  easier  to  interpret.  Drawing  objects,  such  as  text,  lines,  and  arrows 
further  improve  the  readability  of  the  display.  The  Mesh  module  and  other  modules  are  used  to 
create  and  manipulate  numerical  models.  They  allow  (a)  graphical  interaction  with  mesh/grid 
editing,  boundary  conditions,  model  parameters,  and  materials,  and  (b)  visualization  of  numerical 
model  layout,  and  solution  data.  Each  of  the  modules  used  to  create  and  manipulate  numerical 
models  may  have  different  coverages  associations.  For  instance,  the  Mesh  module  has  many 
coverages,  one  for  each  model  supported. 

CGWAVE  CAPABILITIES:  CGWAVE  is  a  general  purpose,  state-of-the-art  finite  element  wave 
prediction  model  based  on  the  elliptic  mild-slope  wave  equation  that  is  applicable  to  harbors,  open 
coasts,  inlets,  islands,  and  fixed  and  floating  structures.  It  includes  the  effects  of  wave  refraction, 
diffraction,  and  dissipation  from  bottom  friction,  wave  breaking,  nonlinear  amplitude  dispersion,  and 
harbor  entrance  losses.  Wave  breaking  can  also  be  added  during  post-processing  if  not  activated 
during  model  execution.  Bottom  friction  is  especially  important  for  long  waves.  CGWAVE  does  not 
have  any  wind  input  or  wave  runup/overtopping  of  structures.  Wave-current  and  wave- wave  inter¬ 
action  processes  are  in  development. 
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CGWAVE  accepts  arbitrary  domains  (Figure  1)  and  structures  using  linear  triangular  finite  elements. 
The  large  number  of  discretized  equations  is  solved  with  iterative  and  direct  solvers  as  a  steady  state 
problem.  Convergence  is  guaranteed,  but  can  be  extremely  slow  on  PC’s  with  large  model  domains. 
The  ERDC  High  Performance  Computing  Center’s  (HPC)  supercomputers  can  be  used  to  quickly 
solve  large  problems.  Currently,  the  Silicon  Graphics,  Inc.  (SGI)  solver  available  on  the  SGI  Origin 
3000  supercomputer  named  “Ruby”  provides  reasonably  fast  run  times  with  CGWAVE.  The  model 
output  is  then  transferred  back  to  the  PC  for  post-processing. 

Both  regular  and  spectral  waves  can  be  input.  Spectral  or  irregular  waves  can  be  simulated  by 
combining  regular  wave  cases.  The  wave  direction  is  the  direction  the  waves  travel  to  and  is 
measured  positive  in  a  counterclockwise  direction  from  east  (i.e.,  0  deg).  Short  and  long  waves, 
including  tsunamis,  can  be  modeled. 
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Additional  information  on  CGWAVE  can  be  obtained  from  Demirbilek  and  Panchang  (1998)  and 
the  Web  site  at  http : /chl.wes .army .mil/research/wave/wavesprg/numeric/wentrances/cgwave.htp . 

STWAVE  vs.  CGWAVE:  What  is  the  difference  between  these  two  numerical  models?  When  do 
you  use  one  instead  of  the  other?  Both  are  used  for  wave  modeling,  but  the  relative  scales  are 
different.  Wave  modeling  can  be  grouped  into  three  classes  or  relative  scales:  generation,  transfor¬ 
mation,  and  local  scale.  The  generation  scale  deals  with  waves  as  they  are  formed  or  generated  in 
deep  water.  The  transformation  scale  describes  wave  transformation  in  deep  to  intennediate  level 
water  depths.  The  finite  difference  STWAVE  model  falls  in  this  class  of  numerical  models  and 
includes  the  coastal  processes  of  refraction,  shoaling,  wave-current  interaction,  wave  growth,  and 
depth-limited  wave  breaking.  The  local  scale  class  is  for  nearshore  or  local  modeling  of  intennediate 
to  shallow  water.  The  finite  element  CGWAVE  model  is  in  this  category.  Thus,  the  STWAVE  can 
be  used  to  transform  deepwater  waves  to  a  depth  coinciding  with  the  offshore  boundary  of  the 
CGWAVE  model. 

CGWAVE  PROCEDURE:  The  procedure  for  running  CGWAVE  within  SMS  can  be  divided  into 
four  parts: 

a.  Create  a  conceptual  model 

b.  Generate  the  finite  element  mesh 

c.  Run  the  model 

d.  Post-process  the  results 

Each  of  these  steps  are  discussed  in  the  following  paragraphs.  Since  SMS  does  not  have  an  “undo” 
function,  it  is  a  good  idea  to  save  your  work  early  and  often. 

CREATE  A  CONCEPTUAL  MODEL:  To  create  the  conceptual  model,  which  SMS  uses  to 
generate  a  mesh-based  numeric  model,  you  should  (a)  import  and  register  a  background  image, 
(b)  gather  coastline  and  bathymetric  data,  (c)  determine  the  coordinate  system  and  datum  reference 
for  the  project,  and  (d)  conceptualize  the  study  area  with  a  CGWAVE  coverage  type. 

Background  Image.  It  is  useful  to  have  an  aerial  photograph  or  image  of  the  project  area  to  see  if 
the  conceptual  model  is  correct.  Image  data  is  input  in  the  Map  module  in  tiff  or  jpg  fonnats  using 
the  File|Open  command.  These  images  have  to  be  registered  or  geo-referenced  to  state  plane 
coordinates,  meters.  The  three  registration  points  shown  in  Figure  2  must  be  moved  to  known 
coordinate  positions  or  a  pre-existing  GIS  type  “world  file”  must  be  read  into  SMS  to  geo-reference 
the  image.  In  this  example,  the  *.jpg  file  was  opened  first  and  then  the  .jgw  world  file  was  input 
using  the  Import  World  File  button.  If  an  SMS  image  file  (.img)  was  previously  saved,  it  can  be 
opened  in  lieu  of  the  world  file  referencing.  The  ASCII  image  file  tcoverlaymetric.img  opens  the 
file  Tedious_small.jpg  and  provides  the  proper  registration  information. 

Coastline  and  Bathymetric  Data.  The  CGWAVE  model  requires  bathymetric  and  coastline 
data.  Bathymetric  data  is  input  in  the  Scatter  module  in  an  “xyz”  file  format,  using  the  File|Open 
command.  The  x  and  y  coordinates  should  be  in  state  plane  and  true  north.  All  values  of  water  depth 
should  be  in  meters  and  positive  downward.  Bathymetry  should  include  the  model  domain  and  a 
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Figure  2.  Registering  image  of  Tedious  Creek,  MD 

sufficient  distance  offshore  to  cover  the  one-dimensional  (1-D)  transects  (see  following  section). 
Sources  of  bathymetric  data  are  previous  studies,  local  surveys,  and  databases  including 
GEODAS,  the  worldwide  geophysics  database.  In  this  study,  survey  data  from  August  2001  were 
available  in  the  file  TediousAugOlharborwaterdepthmeter.xyz  for  the  inner  harbor  and 
Tedcrmllwm.xyz  for  the  offshore  area.  The  bathymetric  data  are  named  elevation,  by  default. 

Coastline  data  defines  the  “wet”  edge  of  the  model  for  the  land-water  interface.  The  data  file 
TediousAugOllandedgesurveymeter.xyz  was  obtained  by  walking  the  bank  line  with  a  hand¬ 
held  global  positioning  system  (GPS)  and  was  used  to  define  the  land  edge.  It  was  also  input  in  the 
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Scatter  module.  Figure  3  shows  the  bathymetry  and  coastline  scatter  sets  overlaid  on  the  background 
image. 

Coordinate  System  and  Datum  Reference.  All  data  must  be  geo-referenced  to  be  useful.  So 
the  bathymetric  and  coastline  data  must  also  be  converted  to  the  same  coordinate  system  to  be 
properly  merged.  A  copy  of  the  “ CORPSCON’ ’  conversion  utility  is  contained  within  SMS.  Since  the 
earth  is  round,  it  is  not  possible  to  have  exact  x/y-coordinates  based  on  latitude  and  longitude.  Thus, 
the  world  is  divided  into  smaller  rectangular  sections  that  permit  more  precise  measurement  in 
horizontal  and  vertical  directions.  The  Web  site  at  the  University  of  Texas  gives  a  good  description 
of  the  different  coordinate  systems  http://www.ncgia.ucsb.edu/education/cirricula/giscc/units/ 
uOl  3  /u0 13.html. 


Figure  3.  Scatter  data  points  representing  bathymetric  survey  locations  for  Tedious  Creek 
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Horizontal  coordinate  systems  supported  within  SMS  are:  (a)  geographic,  (b)  State  Plane, 
(c)  Universal  Transverse  Mercator  (UTM),  and  (d)  NAD  27/83/HPGN  coordinates  in  meters, 
U.S.  survey  feet,  or  international  feet.  Geographic  coordinate  systems  consist  of  latitude,  longitude, 
and  height  measurements,  with  the  prime  meridian  and  the  equator  as  reference  planes  to  define 
latitude  and  longitude.  The  State  Plane  System  was  developed  in  the  United  States  in  the  1930’s  to 
provide  a  national  datum  and  was  based  on  the  North  American  Datum  1927  (NAD  27),  with 
coordinates  in  feet.  In  1 983  the  NAD  27  was  superseded  by  the  NAD  83  system  with  units  in  meters. 
Smaller  states  may  have  only  one  zone,  where  larger  states  may  be  divided  into  several  zones.  UTM 
coordinates  are  composed  of  UTM  zone  numbers  designating  6-deg  longitudinal  strips  and  UTM 
zone  characters  designating  8-deg  latitude  zones.  Vertical  coordinate  systems  support  NGVD  29  or 
NAVD  88  in  meters,  U.S.  survey  feet,  or  international  feet.  The  mean  low  low  water  (mllw)  datum  is 
usually  used.  These  conversions  also  make  sure  all  data  is  aligned  according  to  true  north. 

Figure  4  is  an  example  of  a  single  point  conversion  within  SMS  for  the  offshore  directional 
NORTEK  Aquadopp  wave  gauge  used  in  the  field  measurements  at  Tedious  Creek  during  April  to 
July  2001.  Water  depth  was  2.3  m  (7.5  ft).  The  gauge  was  located  at  lat.  38.24482°  and  long. 
76.03995°.  Click  on  the  Edit|Single  Point  Conversions  command  to  open  the  conversion  routine. 
Values  can  be  input  in  decimal  degrees  or  in  degrees,  minutes,  and  seconds.  The  input  and  output 
horizontal  systems  are  geographic  NAD  27  (US)  and  State  Plane  NAD  27  (US),  respectively.  The 
output  State  Plane  Zone  is  Maryland  -  1900.  These  can  be  determined  using  the  Help  menu  and 


Figure  4.  Single  point  coordinate  conversion 
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locating  the  particular  site  on  the  maps.  The  vertical  system  coordinates  are  not  used  here,  but  still 
must  be  input  correctly.  The  input  and  output  vertical  systems  are  local  and  NGVD  29  (US), 
respectively,  with  a  value  of  7.5  U.S.  survey  feet.  Clicking  the  Convert  button  results  in  anx  value 
of  327884.3540  m,  y  of  461 17.0956  m,  andz  of  2.2860  m. 

In  summary  for  the  Tedious  Creek  project,  all  coordinate  systems  were  converted  to  meters.  The 
horizontal  coordinate  system  is  the  State  Plane  “NAD27  Maryland- 1900,”  and  the  vertical  datum 
reference  is  NGVD  29  (US). 

Conceptualize  Study  Area.  The  conceptual  model  should  define  (a)  the  model  domain, 

(b)  feature  arcs  for  the  coastline  boundary,  open  ocean  boundary,  and  any  additional  structures,  and 

(c)  the  1  -D  transects.  Before  you  begin  to  conceptualize  the  study  area,  create  a  CGWAVE  coverage 
by  selecting  Feature  Objects\Coverages  in  the  Map  module. 

Model  domain.  The  first  step  toward  defining  the  numerical  model  domain  is  having  a  mindset  of 
the  study  purpose  and  the  computational  capability  (processor  speed  and  memory)  to  solve  the 
problem.  The  main  items  of  interest  should  be  within  the  inner  one-third  of  the  model  domain. 
CGWAVE  uses  a  size  function,  which  takes  into  account  the  shortest  expected  wavelength  of 
concern  and  the  water  depth,  to  define  the  required  resolution  for  accurate  computation.  Although 
this  will  be  discussed  in  detail  later,  it  is  a  good  idea  to  do  a  quick  estimate  of  the  anticipated  number 
of  elements. 

Figure  5  shows  the  model  domain  for  the  Tedious  Creek  model.  The  west  or  back  end  of  the  model 
was  truncated  in  water  within  the  harbor  instead  of  the  actual  shoreline  to  reduce  the  number  of 
nodes  and  elements  required.  Because  it  is  marshy  and  shallow  in  the  upper  reaches  of  the  harbor,  it 
was  not  necessary  to  model  these  areas  to  achieve  accurate  results  in  the  study  area. 

Feature  arcs.  Create  the  coastline  arc  by  selecting  Feature  Objects\Create  Coastline.  SMS  will 
automatically  examine  the  bathymetry  contours  to  create  a  feature  arc  at  a  user  specified  elevation. 
Enter  the  minimum  water  depth  to  define  the  coastline  or  land-water  interface.  A  value  of  5  cm  (i.e., 
0.05  m)  is  usually  selected  as  the  coastline  water  depth  to  insure  that  all  elements  are  wet.  Adjust¬ 
ments  can  be  made  in  the  coastline  data  file  to  make  sure  there  are  no  zeros  in  the  definition.  The 
coastline  arc  is  shown  in  brown  in  Figure  5. 

The  ocean  boundary  is  semicircular  for  a  coast,  but  can  be  circular  if  the  domain  is  an  island.  The 
radius  of  the  semicircular  arc  of  the  ocean  boundary  is  selected  to  include  a  distance  up  and 
downcoast  and  offshore  to  permit  sufficient  wave  transformation.  Choose  the  Select  Feature  Vertex 
tool  and  select  two  end  point  vertices  for  the  ocean  boundary  intersection  with  the  coastline  arc.  The 
points  should  be  approximately  equidistant  from  the  center  of  the  harbor.  Be  sure  to  hold  the  shift 
key  down  while  selecting  both  vertices.  The  domain  is  defined  in  the  Feature  Objects|Define 
Domain  command.  Choose  the  semicircular  option  for  a  shoreline.  If  the  arc  is  oriented  landward 
instead  of  offshore,  select  the  arc  to  reverse  direction  using  the  Feature  Objects|Reverse  Arc 
Direction  command  in  the  Map  module.  Since  the  arc  direction  is  determined  by  which  node  of  the 
arc  is  selected  first,  deleting  the  original  arc  and  re-entering  the  two  end  points  in  reverse  order  can 
also  reverse  the  ocean  boundary.  The  semicircular  open  ocean  arc  is  shown  in  blue  in  Figure  5. 
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Figure  5.  CGWAVE  model  boundary  for  Tedious  Creek,  MD 


You  can  further  define  the  area  being  studied  by  creating  additional  feature  arcs.  This  is  done  using 
the  Create  Feature  Arc  tool  in  the  Map  module.  The  Tedious  Creek  model  has  a  feature  arc  at  each 
major  change  in  direction  along  the  coastline  boundary.  In  the  vicinity  of  the  public  piers,  there  are 
many  arcs  to  properly  define  the  piers.  The  coastline  arc  near  the  piers  was  broken  into  several 
unique  arcs  and  vertices  were  moved  to  follow  the  exact  layout  of  the  piers  (see  section  on 
“Reflection  Coefficients”). 

1  -D  transects.  The  1-D  lines  are  used  to  transform  offshore  wave  data  to  the  ocean  boundary  of 
the  model  to  increase  the  reliability  of  the  model’s  predictions  in  projects  where  exterior  bathymetric 
effects  might  play  an  important  role.  In  cases  where  1-D  transformation  is  used,  it  will  no  longer  be 
necessary  to  use  other  spectral  wave  models  to  transform  waves  from  deep  water.  The  CGWAVE 
model  uses  a  1-D  mild  slope  wave  equation  to  solve  for  the  wave  transformation  from  an  offshore 
point  with  known  wave  climate  to  the  CGWAVE  semicircular  ocean  boundary.  The  assumption  is 
that  the  bathymetry  only  changes  in  the  offshore  direction  seaward  of  the  ocean  boundary;  thus, 
simplifying  the  calculations. 

A  1-D  transect  extends  offshore  from  each  side  of  the  model  domain  (Figure  1  and  Figure  5)  with 
origin  at  the  intersection  of  the  semicircular  boundary  and  the  coastline  boundary.  Since  the  ocean 
boundary  is  curved,  the  values  of  wave  transformation  are  input  from  the  transect  which  is  closest  to 
the  point  along  the  semicircular  boundary.  Near  the  center,  the  values  are  averaged  between  the  two 
transects.  Each  transect  includes  bottom  friction  and  reflection,  if  these  processes  are  activated.  It  is 
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important  to  activate  these  processes  unless  the  water  depth  becomes  deep  close  to  shore  (i.e.,  in 
essence  deepwater  waves  at  the  semicircular  boundary)  or  the  depth  is  relatively  constant  all  along 
the  ocean  boundary. 

GENERATE  FINITE  ELEMENT  MESH:  To  generate  a  good  mesh  for  CGWAVE,  you  should 
(a)  define  the  mesh  resolution,  (b)  build  polygons,  (c)  assign  reflection  coefficients,  (d)  create  mesh, 
(e)  check  mesh  quality,  and  (f)  assign  CGWAVE  model  parameters. 

Define  Mesh  Resolution.  The  mesh  in  the  CGWAVE  model  is  wavelength-dependent.  Since 
wavelength  is  a  function  of  the  water  depth  and  wave  period,  it  is  important  to  define  the  design  or 
smallest  wave  periods  of  interest  to  the  proj  ect.  A  minimum  of  6  to  10  elements  in  the  finite  element 
mesh  per  wavelength  is  required  to  properly  define  the  domain.  Fifteen  elements  per  wavelength  is 
ideal.  For  relatively  shallow  projects  like  Tedious  Creek,  this  is  critical  as  the  mesh  may  require  a 
large  number  of  elements,  severely  taxing  the  model’s  capabilities.  Ten  or  more  elements  per 
wavelength  give  the  best  resolution  of  the  wavelengths. 

Size  function.  The  size  function  is  calculated  in  the  Scatter  module.  This  is  a  two-step  process: 
create  the  wavelength  function  and  scale  wavelength  to  create  the  size  function.  The  first  step 
(Figure  6)  is  to  define  and  create  the  wavelength  by  specifying  the  design  wave  period  in  the 
Data|Create  Data  Set  command  of  the  Scatter  module.  Turn  off  all  options  except  for  the 
Transitional  Wavelength  and  Celerity  and  enter  a  value  of  6  sec  for  the  design  wave  period.  This  is 
the  smallest  wave  period  with  significant  energy  and  frequency  of  occurrence  for  the  project  site. 
Make  sure  that  the  water  depth  data  set  (i.e.,  elevation)  containing  the  bathymetry  data  is  active.  Two 
new  data  sets,  Transition  Wavelength  and  Transition  Celerity,  are  created.  The  data  set  name  can  be 
left  with  the  default  Transition  or  other  more  descriptive  name.  The  Transition  Celerity  data  set  is 
not  needed  and  can  be  deleted  in  the  Data  Browser  if  desired. 

The  next  step  (Figure  7)  is  to  create  a  size  function  data  set  based  on  the  Transition  Wavelength  in 
the  Data  Calculator  command.  Select  the  Transition  Wavelength,  the  divide  symbol  and  enter  the 
value  of  10  in  the  formula  box.  Define  the  new  computed  data  set  as  something  like  SizelO_T6  in 
the  Result  box  to  document  and  click  on  the  Compute  command.  This  new  data  set  will  be  used  in 
calculating  the  finite  element  mesh  resolution  so  that  the  element  edges  have  a  length  of  the  order  of 
this  maximum  size.  The  mesh  will  be  denser  where  the  size  values  are  smaller. 

Build  Polygons.  The  second  step  in  the  generating  finite  element  mesh  is  to  build  the  polygons. 
Switch  to  the  Map  module  and  select  the  Feature  Objects|Build  Polygons  command  to  construct 
polygons  from  the  feature  arcs.  The  File|Get  Info  command  or  the  Get  Module  Info  button  on  the 
toolbar  will  bring  up  a  dialog  that  will  tell  you  how  many  polygons  were  created.  In  this  example, 
there  should  be  three  polygons:  one  for  the  ocean  and  two  for  the  detached  breakwaters. 

Once  you  have  created  polygons,  you  can  use  the  Select  Feature  Polygons  tool  to  select  individual 
polygons.  Activate  the  Select  Feature  Polygons  tool,  and  double  click  a  polygon  to  bring  up  the 
Polygon  Attributes  dialog.  This  dialog  allows  you  to  set  various  options,  which  SMS  will  use  to 
create  the  finite  element  mesh.  If  Mesh  Type  ox  Bathymetry  Type  is  set  to  an  option  that  is  dependant 
on  a  scatter  set,  a  Scatter  Options  button  will  appear  below  the  combo  box,  allowing  the  user  to 
select  further  options. 
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Figure  6.  Creating  a  wavelength  function  for  a  wave  period  of  6  sec 

Ocean  polygon.  For  the  ocean  polygon  (Figure  8),  set  the  Mesh  Type  to  Scalar  Paving  Density. 
This  tells  SMS  to  generate  a  mesh  with  a  density  interpolated  from  a  size  scatter  set.  Click  the 
Scatter  Options  button  to  open  the  Interpolate  window.  Select  SizelO_T6  for  the  Scatter  Set  to 
Interpolate  From,  Linear  for  the  Interpolation  Option,  and  Single  Value  with  a  value  of  0.0  for  the 
Extrapolation  box. 

For  the  Bathymetry  Type,  input  Scatter  Set  to  indicate  that  the  mesh  elevations  will  be  interpolated 
from  scatter  set  data.  Once  again,  a  Scatter  Options  button  will  appear  and  selecting  this  button 
brings  up  a  similar  Interpolation  dialog.  The  same  input  as  before  should  be  entered  except  that  the 
elevation  data  set  should  be  input  for  the  Scatter  Set  to  Interpolate  From. 

Finally,  the  Polygon  Type/Material  is  input  as  Ocean. 

Breakwater  polygons.  The  other  two  polygons  represent  the  detached  breakwater  polygons.  The 
attributes  for  these  polygons  will  have  a  Mesh  Type  of  None  and  the  Polygon  Type/Material  as 

Land. 
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Figure  7.  Create  size  function  using  data  calculator 

Reflection  Coefficients.  The  third  step  is  to  assign  the  reflection  coefficients.  Values  range  from 
0.0  for  no  reflection  (i.e.,  complete  transmission)  to  1.0  for  complete  reflection.  Typical  reflection 
coefficients  for  marshy  shorelines  and  rubble-mound  breakwaters  are  0. 1  and  0.5,  respectively.  The 
public  piers  at  Tedious  Creek  were  constructed  using  vertical  sheet-pile  walls  that  did  not  extend  to 
the  bottom.  The  appropriate  reflection  coefficient  of  0.9  was  assigned  for  them.  In  the  Map  module, 
activate  the  Select  Feature  Arc  Tool  and  double  click  on  each  arc  to  set  the  appropriate  reflection 
coefficient.  This  process  is  illustrated  in  Figure  9.  Thompson  et  al.  (1996)  provides  a  good  reference 
for  typical  reflection  coefficients  for  short  waves. 
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Figure  8.  Defining  attributes  for  polygon  representing  ocean  material  type 
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Figure  9.  Assigning  unique  reflection  coefficients  to  public  piers 
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Create  Mesh.  This  is  potentially  a  long  process,  depending  on  the  size  function  and  the  extent  of 
your  domain.  It  is  a  good  idea  to  save  your  work  first  using  the  File|Save  command.  Then,  select  the 
Feature  Objects|Map  to  2D  Mesh  command  to  begin  the  mesh  generation. 

Figure  10a  and  10b  illustrate  the  section  of  the  created  Tedious  Creek  CGWAVE  mesh  in  the 
vicinity  of  the  public  piers  and  north  breakwater.  It  illustrates  the  finite  element  mesh  based  on  the 
T  =  6  sec  wave  period  and  a  size  function  defined  by  one  tenth  of  the  wavelength.  The  mesh  contains 
a  total  of  339,042  elements  and  171,265  nodes. 

The  primary  purpose  of  this  Tedious  Creek  study  was  to  compare  existing  and  authorized  breakwater 
configurations.  Figure  1 1  shows  the  two  breakwater  lengths  relative  to  the  channel  outlines  (red 
outlines).  To  accomplish  this,  a  different  mesh,  using  the  same  size  function  definitions,  with  the 
revised  arcs  representing  the  altered  breakwater  alignments,  was  created. 

Check  Mesh  Quality.  Element  and  mesh  quality  can  be  checked  using  the  CGWAVE  |  Model 
Check  command  in  the  Mesh  module.  A  mesh  should  have  certain  properties  to  insure  that  it  runs 
efficiently  during  execution  and  does  not  cause  instabilities  in  the  solution.  It  should  have  good  (a) 
elemental  properties,  (b)  smooth  bathymetric  contours,  (c)  gradual  area  change,  and  (d)  mild 
longitudinal  depth  changes.  The  elemental  properties  include  aspect  ratio,  shape,  and  angle.  An  ideal 
element  has  an  aspect  ratio  with  sides  that  are  the  same  length,  no  thin  triangles,  and  interior  angles 
greater  than  10  deg.  Adjacent  elements  should  not  have  area  or  depth  changes  greater  than  20 
percent  and  should  follow  depth  contours.  If  the  Model  Check  does  not  return  any  serious  errors, 
proceed  to  assign  CGWAVE  model  parameters. 

Assign  Model  Parameters.  Defining  the  CGWAVE  model  parameters  is  a  two-step  process: 
(a)  renumber  nodestrings,  and  (b)  input  model  control  parameters. 

Renumber  nodestrings.  Nodestrings  are  subsets  of  sequential  nodes  that  allow  specific 
parameter  assignments  and  operations.  SMS  automatically  creates  nodestrings  from  the  feature  arcs 
when  it  generates  the  mesh.  The  nodestrings  should  retain  the  properties,  such  as  reflection 
coefficients,  that  were  already  assigned  to  the  feature  arcs  so  all  you  need  to  do  is  renumber  them. 
Renumbering  gives  new  numbers  to  all  the  nodes  in  an  orderly  fashion  to  improve  numerical 
bookkeeping.  It  only  has  to  be  done  once  after  all  mesh  editing  is  finished.  Typically,  the  best 
renumbering  location  is  the  ocean  boundary  nodestring.  The  mesh  is  renumbered  by  selecting  the 
Nodestrings  |  Renumber  command  from  the  Elements  menu  after  having  selected  a  nodestring.  The 
nodestring  is  used  as  a  seed  to  start  the  renumbering  process.  The  bandwidth  option  is  the  default. 

Input  model  control  parameters.  Input  the  model  control  parameters  by  selecting  the 
CGWAVE  |  Model  Control  command  in  the  Mesh  module.  These  include  sections  on  (a)  incident 
wave  conditions,  (b)  nonlinear  wave  options,  (c)  open  boundary,  (d)  1-D  wave  transfonnation  inputs, 
and  (e)  numerical  solver.  Incident  wave  conditions  are  input  along  the  open  ocean  boundary  and 
include  wave  period,  direction,  and  amplitude.  The  amplitude  is  one  half  the  wave  height,  and  should 
not  be  confused  with  the  wave  height.  Nonlinear  wave  options  include  bottom  friction,  wave 
breaking,  and  nonlinear  dispersion.  When  first  debugging  a  model,  it  is  best  to  do  the  simple  cases 
first.  Then,  a  sensitivity  analysis  can  be  performed  with  these  wave  options  to  determine  which 
should  be  exercised.  Open  boundary  conditions  should  match  those  selected  when  generating  the 
domain  in  the  Map  module.  These  are  semicircular  in  the  Tedious  Creek  example. 
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a.  CGWAVE  mesh  and  bathymetry  in  vicinity  of  public  piers 


mmgg&mgBsm 


b.  Bathymetry  and  mesh  in  vicinity  of  north  breakwater  for  existing  configuration 


Figure  10.  CGWAVE  mesh  and  bathymetry  details  in  vicinity  of  public  piers 
and  breakwater 
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Figure  11.  Schematic  of  existing  breakwater  configuration  (121.9-m  (400-ft)  gap)  versus  red  outline  of 
authorized  breakwater  alignment  (91 .4-m  (300-ft)  gap)  with  respect  to  channel  outline 

In  the  1-D  section,  the  user  can  specify  either  the  number  of  nodes  or  the  spacing  in  the  1-D  lines. 
The  spacing  should  be  of  the  order  of  the  smallest  element,  typically  closest  to  the  coastline,  on  the 
semicircle.  A  rule  of  thumb  is  that  it  is  1 .25  times  the  offshore  boundary  radius  divided  by  100.  The 
length  of  1-D  lines  should  extend  sufficiently  offshore,  and  may  extend  to  the  limits  of  the  existing 
scatter  set  or  further  extended  to  pick  up  waves  from  buoys  located  beyond  the  scatter  set.  After 
selecting  appropriate  accuracy,  the  user  selects  either  the  “#l-d  nodes”  or  the  “1-d  spacing”  in  the 
Compute  section  to  calculate  and  save  the  1-D  lines  (assuming  the  “Save  1-d  file”  under  “Open 
Boundary”  has  been  selected). 

Finally,  the  numerical  solver  should  be  selected  for  the  machine  performing  the  calculations.  If  the 
model  is  small  enough  for  the  PC,  then  the  “0  (or  1)  Standard  (PC)”  solver(s)  is  selected.  Otherwise, 
the  “2  SGI  Parallel”  solver  for  the  HPC  Ruby  SGI  processor  should  be  selected.  There  are  different 
solvers  for  different  HPC  supercomputers,  however. 

RUN  MODEL:  Before  running  the  model,  save  your  file  and  make  an  additional  backup  copy  with  a 
different  name  in  case  the  file  becomes  corrupted.  Select  File  |  Save  As  to  save  the  file  as  a  project 
file  with  suffix  *.spr.  All  geometry,  input,  and  mesh  information  is  contained  in  this  file. 


16 


ERDC/CHL  CHETN-l-68 
March  2004 

ERDC  MSRC  Resources.  CGWAVE  can  be  run  from  within  SMS,  but  may  be  “painfully”  slow 
depending  on  the  size  of  your  mesh.  To  run  on  your  PC,  select  CGWAVE  |  Run  CGWAVE.  To  run 
on  the  HPC  Ruby  SGI  processor,  you  must  have  (a)  Kerberos  software  (latest  Version  20030506b 
for  Windows)  to  insure  secure  communications  between  your  PC  and  Ruby,  (b)  a  SecurlD  card  for 
obtaining  a  “ticket”  to  use  the  MSRC  resources,  (c)  telnet  software  such  as  PuTTYtel  (telnet)  and 
(d)  file  transfer  (i.e.,  FTP)  capability,  such  as  windows-based  Filezilla.  The  latest  version  of  the 
Kerberos  software  and  telnet/ftp  software  can  be  downloaded  from  the  MSRC  Web  site  at 
http://kirby.hpcmp.hpc.mil.  The  Documentation  tab  on  the  left  side  of  the  screen  is  useful  for  details 
on  the  procedure.  The  ERDC  MSRC  Customer  Assistance  Hotline  at  601-634-4400,  option  1  is 
particularly  helpful.  Your  CGWAVE  files  can  then  be  copied  to  the  Ruby  (ASCII  mode),  executed, 
and  then  copied  back  to  your  PC  for  post-processing  within  SMS. 

HPC  Ruby  Access.  The  first  step  is  to  gain  permission  to  use  the  MSRC  resources.  All  examples 
in  this  technical  note  assume  the  UNIX  6.5  shell.  For  the  UNIX  environment,  it  is  advisable  to  have 
filenames  without  imbedded  blanks.  The  University  of  Texas  maintains  a  Web  site  with  a  good 
introduction  to  UNIX  that  is  accessible  at  www.utexas.edu/cc/unix/index.html. 

Initially,  Kerberos  and  Filezilla  software  are  used  to  copy  two  SMS  output  files  from  your  PC  to 
Ruby.  These  ASCII  files  are  the  CGWAVE  run  control  input  file  (i.e.,  *.cgi)  and  the  ID  (*.cgl)  file. 
The  asterisk  is  a  placeholder  for  the  project  prefix  selected  for  the  study.  After  successful  transfer  of 
these  files,  a  PuTTy  telnet  session  to  Ruby  is  required  to  issue  UNIX  based  commands.  The  two 
input  file  names  need  to  be  renamed.  The  first  file  *.cgi  must  be  renamed  to  be  *.dat  and  the  *.cgl 
file  must  be  renamed  to  *.  Id.  This  is  accomplished  with  the  copy  UNIX  command  that  follows  the 
format,  “cp  oldfile  newfile”. 

CGWAVE  Execution.  There  are  four  steps  for  executing  CGWAVE  within  Ruby  including 
(a)  edit  input  file  *.dat,  (b)  convert  input  to  binary,  (c)  run  CGWAVE,  and  (d)  convert  output  to 
ASCII. 

Edit  the  “*  .dat”  file,  to  reflect  changes  in  incident  wave  period,  amplitude,  and  wave  direction  in  the 
title  (for  documentation)  and  the  corresponding  input  field  near  the  beginning  of  the  file.  Use  the  line 
editor  “ed”  or  the  full  screen  editor  “vi”  within  the  UNIX  environment.  A  quick  reference  guide  for 
the  vi  editor  is  http://cac.uvi.edU/miscfaq/vi-cheat.html#toc. 

The  second  step  is  to  convert  the  input  ASCII  run  control  file  from  SMS  to  binary  format.  The  utility 
program  dat2unf  performs  this  conversion  and  creates  three  files  *.par,  *.geo,  and  *.grd  corre¬ 
sponding  to  the  input  parameter,  geometry,  and  grid  files,  respectively. 

The  third  step  is  run  CGWAVE  using  the  executable  file  “pegw  sgi  ser”.  This  is  the  serial  version 
for  the  SGI  processor  Ruby  (i.e.,  same  as  option  2  under  CGWAVE  \  Model  Control  described 
earlier).  This  is  the  main  program  that  does  the  CGWAVE  calculations.  CGWAVE  runs  usually 
required  less  than  5  min  to  complete  up  to  eight  iterations.  Thus,  the  serial  version  was  adequate  for 
the  size  of  this  model.  Larger  models  would  benefit  from  HPC’s  parallelized  codes  and  solvers. 

The  fourth  step  is  to  convert  the  binary  output  file  *000 1  .res  generated  from  the  third  step  to  ASCII 
using  the  utility  program  res2out_sgi.  The  output  file  *  .out  from  this  program  can  then  be  transferred 
in  ASCII  mode  to  your  PC  via  Filezilla  FTP.  It  is  a  good  idea  to  copy  this  output  file  to  your  home 
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directory  on  the  Ruby  with  a  descriptive  name  and  suffix  “.ego”  before  transferring  to  your  PC. 
SMS  recognizes  this  file  extension  better  than  the  *.out  suffix.  The  *.che  file  is  a  documentation  file 
recorded  during  each  CGWAVE  run  (i.e.,  the  pcgw  command)  to  show  the  resolution  obtained  after 
each  iteration.  It  should  also  be  saved  and  transferred  to  your  PC  for  future  reference. 

The  final  step  after  each  run  is  to  purge  the  miscellaneous  files  in  the  Work  directory  before 
executing  an  additional  run.  The  user  can  create  a  short  cut  command  in  the  alias  file.  For  Tedious 
Creek,  a  short  cut  command  “rmtcall”  was  created  to  remove  these  files  so  that  they  could  be  reused. 
The  up  arrow  command  works  for  cycling  through  all  commands  executed  during  a  telnet  session 
on  Ruby.  This  is  helpful  if  multiple  runs  are  planned,  so  that  the  commands  do  not  have  to  be  typed 
in  again.  After  all  runs,  type  Exit  and  carriage  return  twice  to  exit  Ruby. 

POST-PROCESS  RESULTS:  CGWAVE  calculates  scalar  and  vector  output  information.  Scalar 
data  include  wave  height,  phase,  sea  surface,  dynamic  wave  pressures  at  three  depths,  and  wave 
surface  data.  Vector  data  include  particle  velocity  at  three  depths,  wave  direction,  and  wave  velocity. 
Usually,  the  wave  height  and  phase  are  the  primary  scalar  quantities,  and  wave  direction  the  primary 
vector  quantity  of  interest. 

Results  from  the  CGWAVE  runs  can  be  post-processed  in  SMS.  The  first  step  is  to  FTP  the  ASCII 
result  files  to  your  PC  using  the  Filezilla  software.  The  next  step  is  to  import  the  *.cgo  data  files  in 
the  Data  Browser  |  Import  command  of  SMS. 

Visualization  methods  in  SMS  include  contour  plots,  vector  plots,  animations,  and  plots  of  obser¬ 
vation  data.  The  display  options  tool  can  be  used  to  quickly  access  contour  and  vector  display 
options. 

Contours.  To  view  contours  of  scalar  data  within  SMS,  select  the  2D  Mesh  tab  in  the  Display 
Options  dialog  and  turn  on  the  Contours  toggle.  The  Contour  Options  tab  controls  how  the  contours 
will  be  displayed.  Contours  can  be  linear,  filled,  or  combined.  The  range  and  either  the  number  or 
size  of  intervals  can  be  specified.  When  you  exit  the  dialog,  the  display  will  update  with  contours 
corresponding  to  the  active  scalar  data  set. 

Vectors.  To  view  a  vector  plot  within  SMS,  turn  on  the  Vectors  toggle  on  the  2D  Mesh  tab  of  the 
Contour  Options  dialog.  The  Vectors  tab  allows  you  to  specify  head  size,  arrow  length,  colors,  and 
placement  of  vectors.  The  vectors  will  be  displayed  according  to  the  active  vector  data  set. 

Animations.  Animations  can  be  created  within  SMS  from  the  time-steps  that  are  imported  for  each 
solution.  A  series  of  wave  height  contours  or  wave  direction  vector  plots  are  formed  to  create  the 
animation  with  the  number  of  frames  detennined  by  the  user.  To  create  an  animation,  select  the  Film 
Loop...  item  from  the  Data  menu  in  the  Mesh  module.  An  animation  wizard  will  guide  you  through 
the  process  of  creating  a  film  loop.  The  film  loop  will  be  saved  as  an  .avi  file  that  can  be  viewed 
from  within  SMS  or  used  with  other  software  such  as  Microsoft  PowerPoint. 

Observation  Plots.  An  observation  coverage  can  be  created  to  look  at  a  cross  section  of  wave 
heights  along  a  user-defined  transect.  Data  can  be  plotted  within  SMS  and  saved  for  further  post¬ 
processing  with  other  software  (i.e.,  Axum,  Excel,  etc.). 
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POINTS  OF  CONTACT :  For  additional  information  or  to  obtain  executables  for  the  HPC  Ruby, 
contact  Dr.  Michael  J.  Briggs  (Voice:  (601)  634-2005,  e-mail:  Michael. J.Briggs@erdc. 
usace.army.mil);  Ms.  Barbara  Donnell  (Voice:  (601)  634-2730,  e-mail:  Barbara.Donnell@erdc. 
usace.army.mil),  or  Dr.  Zeki  Demirbilek  (Voice:  (601)  634-2834,  e-mail:  Zeki.Demirbilek@erdc. 
usace.army.mil. 
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